Skip to content

Sync the skill with the shipped CLI (v0.0.27) - #4

Closed
arhangel66 wants to merge 3 commits into
mainfrom
fix/ps-json-gotcha
Closed

Sync the skill with the shipped CLI (v0.0.27)#4
arhangel66 wants to merge 3 commits into
mainfrom
fix/ps-json-gotcha

Conversation

@arhangel66

Copy link
Copy Markdown
Collaborator

The skill states in four places that lium ps does not support --format json, including a gotcha section showing an invented error message:

lium ps --format json  # Error: No such option

It does support it, and has since v0.0.13 — the current release is v0.0.27. Verified against the installed binary:

$ lium ps --help
  --format [table|json]  Output format. 'json' emits machine-readable JSON to
                         stdout (suitable for piping to jq).

The cost is real: an agent that believes this parses the Rich table, or drops to the SDK for something the CLI already answers, and never machine-reads pod state — ports included.

Changes:

  • the gotcha section is replaced by the advice that was actually load-bearing in it: target pods by name/huid, not by row number, because indices shift;
  • the "Output Formats" section now states the real spread — ls and ps take --format json, balance takes --json, templates has neither;
  • the end-to-end workflow verifies with lium ps --format json instead of a comment repeating the claim;
  • llms-full.txt regenerated.

The one remaining "no --format json" note, on lium templates, is accurate — checked.

@arhangel66

Copy link
Copy Markdown
Collaborator Author

Swept the rest of the machine-readable-output claims. Walked the whole command tree of the installed binary and cross-checked every option against the v0.0.27 tag. The real map:

Flag Commands
--format table|json ls, ps — and nothing else
--json balance, fund crypto currencies, fund crypto invoice
--json on the group provider …, inherited by all ~25 subcommands
none templates, volumes, schedules, ssh-keys, exec, logs, bk, config, up, rm, ssh, scp, rsync, reboot, update, port-forward, init

Two more inventions found and fixed:

csv does not exist. cli-commands.md offered --format FORMAT Output format (table, json, csv) for both ls and ps. lium ls --format csv exits with a usage error — the choice is [table|json].

The ls and ps option lists were largely fictional. ls was documented with --region, --min-memory, --max-price and a positional GPU_TYPE; it has none of them — the real filters are --gpu, --count, --min-cuda, --lat/--lon/--max-distance, --sort, --limit. ps was documented with -a/--all and --sort FIELD; it has neither, only an optional pod id and --format. Both blocks now match the CLI, and the example lium ls --max-price 2.5 is gone.

SKILL.md now carries the table above instead of a one-line summary, and llms-full.txt is regenerated.

Deliberately not documented yet: exec --json landed in DAH-2556 on main but is not in v0.0.27, so the skill would be promising a flag users do not have.

Out of scope for this PR, worth its own pass: the inventions are not limited to output formats — lium ssh is documented with --command, --port and --key, and it takes none of them. A full sweep of cli-commands.md against the CLI is a separate change.

@arhangel66

Copy link
Copy Markdown
Collaborator Author

Full sync pass. Method: checked out the v0.0.27 tag, loaded the Click tree programmatically and dumped every command with its real arguments and options — 93 commands — then checked the skill against that dump rather than against memory.

Commands whose documented options did not exist

Command Was documented Reality in v0.0.27
ssh --command, --port, --key takes a target and nothing else
exec --timeout, --output -s/--script, -e/--env
scp -r/--recursive, -p/--preserve only -d/--download
rsync --delete, --exclude, --dry-run no options at all
reboot -v/--volume -a/--all, --volume-id
bk set / bk restore positional PATH / BACKUP_ID --path, --id flags
schedules rm takes a pod takes indices from schedules list
theme interactive if omitted; monokai/solarized/dracula/nord name is required; only dark and light exist
global --config PATH, --debug neither exists — only --version, --help
env vars LIUM_SSH_KEY does not exist (LIUM_BASE_URL does, and is useful for staging)

rm --in / --at were described as name and executor filters; they schedule the removal after a duration or at a time.

Wrong in the other direction

lium init was marked "NOT suitable for agent/scripted use — has no non-interactive flags" while SKILL.md documents the headless flow two sections earlier. It has --no-browser and --session; the reference now says so.

Commands that were missing entirely

balance, topup currencies, topup create, update, ssh-keys — all agent-relevant, none documented. Added.

Exit codes

The table promising codes 1–6 describes main, not the shipped CLI. In v0.0.27 there is no exit-code contract at all: lium ps <unknown-id> exits 0. Verified by running it against the tagged code. The section now states that plainly and keeps the table as what lands in the next release.

Smaller fixes

  • lium ls H100 — there is no positional GPU argument, only --gpu;
  • --sort default is download, not price_gpu;
  • the --json row of the output table named fund crypto currencies / fund crypto invoice, which do not exist — the real ones are fund, topup currencies, topup create;
  • sdk-reference.md: lium.exec(pod, "cmd")command is keyword-only, so the positional form raises TypeError.

Verification

Wrote a checker that extracts every lium … example from the skill and validates each command path and flag against the dump. All examples pass; the only two hits left are prose lines that begin with the word "lium". Every SDK method named in sdk-reference.md exists in v0.0.27, and the call signatures now match.

The checker is a throwaway script, not part of this PR. Worth landing as a CI check next to check-llms-full so the reference cannot drift again — that is its own change.

@arhangel66 arhangel66 changed the title Fix: the skill tells agents lium ps has no --format json Sync the skill with the shipped CLI (v0.0.27) Aug 5, 2026
@arhangel66

Copy link
Copy Markdown
Collaborator Author

Superseded by #5, which re-verifies the same claims against v0.0.29 and carries the sdk-reference.md fix from here. Closing.

@arhangel66 arhangel66 closed this Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant